Skip to content

feat: Add REST API and Web UI for remote time tracking #373

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: dev
Choose a base branch
from
Open

feat: Add REST API and Web UI for remote time tracking #373

wants to merge 1 commit into from

Conversation

@av1m
Copy link

@av1m av1m commented Oct 21, 2025

📱 What does this PR do?

Adds a local REST API server and web interface that allows users to track time from their computer browser while keeping data synced with the Android app in real-time.

This addresses the sync and web UI feature request from issue #103.

🎥 A screen recording that show the feature

✨ Features Added

REST API Server

  • Lightweight HTTP server using NanoHTTPD
  • Reuses existing Wear OS API (WearCommunicationAPI) - zero duplicate code
  • Local network only - no cloud dependency, privacy-focused
  • Auto-starts on app launch (can be disabled)

Web Interface

  • 📋 View all activities with colors and icons
  • ▶️ Start/Stop tracking with one click
  • ⏱️ Live timers with real-time countdown
  • 📊 Statistics dashboard showing today's activity
  • 📜 Activity history with recent records
  • 🌓 Dark mode support
  • 📱 Responsive design for mobile and desktop
  • 🔄 Auto-refresh every 2 seconds

🔧 Technical Implementation

API Endpoints

  • GET /api/activities # List all activities
  • GET /api/running # Currently running timers
  • POST /api/start/:id # Start activity
  • POST /api/stop/:id # Stop activity

Files Added/Modified

New files:

  • app/src/play/java/.../api/WebApiAdapter.kt - REST API implementation
  • app/src/play/java/.../api/WebApiModule.kt - Dependency injection
  • web/index.html - Sample of WebApp (we just use API)

Modified files:

  • app/src/main/java/.../TimeTrackerApp.kt - Start API server on app launch
  • app/src/main/AndroidManifest.xml - Add INTERNET permission

🎯 Why This Approach?

  1. Code Reuse: Leverages existing WearCommunicationAPI - no duplicate business logic
  2. Consistency: Web UI and Wear OS behave identically
  3. Maintainability: Changes to core logic automatically work for both integrations
  4. Privacy: Local network only, no cloud services required
  5. Optional: Only in play flavor, doesn't affect base (F-Droid) build

📝 Usage

  1. Install the app (play flavor)
  2. Find phone's IP address (Settings → About → IP Address)
  3. Open web/index.html in browser on computer
  4. Enter http://[phone-ip]:8080 and click "Connect"
  5. Start tracking from your computer! 🎉

🔒 Security Considerations

  • Local network only - not exposed to internet
  • No authentication (for now) - assumes trusted network
  • Same WiFi required - phone and computer must be on same network
  • Future enhancement: Add optional API key authentication

🐛 Known Limitations

  • Web UI is read-only for tags (cannot create/edit tags from web)
  • Statistics calculated from running activities (not full history)
  • If the app is closed, the server not work
  • No WebSocket support (uses polling instead)
  • Only available in play flavor (depends on Google Play Services components)

@av1m av1m mentioned this pull request Oct 21, 2025
Open
@AnonMiraj
Copy link

AnonMiraj commented Nov 4, 2025

Looks really cool!
I’ve wanted to try implementing something similar for a long time.
Reusing the core logic from WearOS is very smart.
Would it be possible to enable this in the base F‑Droid build by refactoring so both Wear OS and the web UI depend on a shared base implementation? Or is it heavily dependent on Google services?

@av1m
Copy link
Author

av1m commented Nov 5, 2025

Yes @AnonMiraj, this can definitely work in the F-Droid build!

The web UI doesn't actually depend on Google services; it uses NanoHTTPD (standalone library) and local networking only. The note about Google Play Services dependency might be misleading.

To enable F-Droid support:

  1. Extract WearCommunicationAPI to a shared module (e.g., core or :feature_remote_api)
  2. Move web API files from app/src/play/ to app/src/base/ or the shared module
  3. Keep WearOS-specific code (actual Google Play Services deps) in app/src/play/

Result:

  • Base (F-Droid): Core API + Web UI
  • Play: Base + WearOS

I'm happy to refactor this PR to support both flavors if desired, or we can merge as-is (play-only) and handle it later.
Let me know your preference @Razeeman!

Razeeman
Razeeman reviewed Nov 5, 2025
View reviewed changes
app/src/main/AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">

<uses-permission android:name="android.permission.INTERNET" />
Copy link
Owner

@Razeeman Razeeman Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you very much for this PR, looks very cool!

Unfortunately the only guarantee of data privacy is not having an internet permission. Is it possible to implement this feature without adding it?

Copy link

@fchedemail fchedemail Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @Razeeman,

I don't want to reply in place of @av1m, but I don't think this kind of feature is realistically doable without this permission. I'm no Android dev, but the documentation states that this permission is required to open a network socket, so any LAN communication would require this permission (unless using bluetooth or some other exotic communication channel I guess).

However, as this PR currently is, this feature would only be available in the play flavor of the app which nicely solves this "data privacy guarantee" conundrum. In my opinion, in the same way Wear OS support was handled & merged, this feature could be play flavor only. "Privacy wary" people could use or keep using the F-Droid version (which they probably already use), without this feature nor the internet permission in the manifest.

As far as I'm concerned, I understand how not asking for this permission is a quick and easy way to "guarantee" no data leakage over the internet. However, there are other ways to guarantee this (reviewing the source code, sandboxing the app, using something akin to https://reports.exodus-privacy.eu.org, etc.) and other way the data could be poorly handled / leaked. In my opinion, my data in this app is far from critical anyway, so I'm not asking for the highest level of security guarantees anyway. The usefulness of a very convenient feature like this one outweighs the potential privacy concerns. I also understand that as a maintainer and being the creator of the app, you may disagree :)

Cheers,
Florian

Copy link
Owner

@Razeeman Razeeman Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is one workaround, although not looked into it much, but could be possible. Is to have a separate app, like a plugin, that would be installed separately and would have internet permission, it work with time tracker app and pass data to it. If I'm not mistaken, if both apps signed with the same signing key, they are basically the same app, and can share data without permissions. So it would work like this: time tracker pass data to plugin app, plugin app calls web api. Hope this makes sense.

The downside is that it probably wouldn't be possible to publish this plugin app on google play (I saw apps like this removed). It could be possible to publish it on f-droid and it will be available as an apk on github.

@YIRU69
Copy link

YIRU69 commented Nov 9, 2025

I'm really looking forward to this feature.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Razeeman Razeeman Razeeman left review comments

+1 more reviewer

@fchedemail fchedemail fchedemail left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@av1m @AnonMiraj @YIRU69 @Razeeman @fchedemail